home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / demos / commercial / rexxvar_demo.lzh / RexxVar_Demo / ReadMe < prev   
Encoding:
Text File  |  1994-02-14  |  14.4 KB  |  384 lines

  1.   Copyrights and Credits
  2.   
  3.      Copyright 1994 AugmenTek
  4.         All Rights Reserved
  5.      
  6.      AugmenTek
  7.      3606 S. 180th St. C-22
  8.      SeaTac, WA 98188
  9.      USA
  10.      
  11.      Phone: 206-246-6077
  12.      email: augmentek@acm.org
  13.   
  14.   
  15.      AmigaGuide, AmigaGuide.info, amigaguide.library, WDisplay, WDisplay.info
  16.      (c) Copyright 1992 Commodore-Amiga, Inc.  All Rights Reserved.
  17.      Reproduced and distributed under license from Commodore.
  18.      
  19.      Installer and Installer project icon
  20.      (c) Copyright 1991-93 Commodore-Amiga, Inc.  All Rights Reserved.
  21.      Reproduced and distributed under license from Commodore.
  22.   
  23.      AMIGAGUIDE AND INSTALLER SOFTWARE IS PROVIDED "AS-IS" AND SUBJECT TO CHANGE;
  24.      NO WARRANTIES ARE MADE.  ALL USE IS AT YOUR OWN RISK.  NO LIABILITY OR
  25.      RESPONSIBILITY IS ASSUMED.
  26.   
  27.      ARexx is a trademark of Wishful Thinking Development Corp.
  28.   
  29.      This archive is freely redistributable only with all parts included.
  30.   
  31.   Introduction
  32.   
  33.      This is a demonstration version of the commercial RexxVar product from
  34.      AugmenTek.
  35.   
  36.      RexxVar makes coding REXX programs easier by providing a familiar and quick
  37.      means of exchanging variable values with  AmigaDOS commands and programs.
  38.   
  39.      This is a "crippled" demo version, limited in the amount of data that can be
  40.      exchanged between REXX variables and commands.  In some cases, it may also be
  41.      slower than the commercial version. In addition, the facility to extract
  42.      meaningful error codes (the REXXVAR_RC function host) is disabled and the
  43.      error code variable will always be "?". When a limit is exceeded, you will
  44.      normally see the following error message in the RexxVar_Server's window:
  45.   
  46.           Not enough storage
  47.   
  48.      The full version is not limited in value lengths (except for ARexx's
  49.      limitations), allows access to a command's meaningful error code, has
  50.      performance comparable to ARexx's for variable creation, and provides online
  51.      documentation via AmigaGuide.
  52.   
  53.      1.  Double-click on the "Install.RexxVar" icon to install, or type:
  54.   
  55.               Installer Install.RexxVar
  56.   
  57.      2.  After installation, there are some examples below you can run.  You can
  58.          use your own, but you must keep in mind that variable value lengths in
  59.          this demo are limited to 25 bytes, the maximum number of stem array
  60.          elements are 25, and that using stem array elements may be slow.
  61.   
  62.          First, some let's define some terms.
  63.   
  64.          "Integer indices" mean that the index to a stem array ranges from 1 to n
  65.          (by 1).  "n" is the total number of values and is also found in "stemname.0"
  66.          (where "stemname" is the name of the stem array).
  67.   
  68.          "Arbitrary indices" mean that the index to a stem array can be any string.
  69.          These indices are usually saved in a variable (separated from each other
  70.          by a delimiter character), so that all elements that have values are
  71.          remembered.
  72.   
  73.          A "variable" is any valid ARexx variable symbol that does not end with a
  74.          period; names ending in periods are called "stemnames"
  75.   
  76.          "Redirection" is when you use ">filename" for directing command output to
  77.          that filename, "<filename" for command input, or ">>" for appending
  78.          command output.
  79.   
  80.   Examples
  81.   
  82.      1.  Sorting
  83.   
  84.          a.  stem array, integer indices, stemname.0 = number of values
  85.   
  86.                   line.1 = 'cat'
  87.                   line.2 = 'bat'
  88.                   line.3 = 'at'
  89.                   line.0 = 3
  90.                   Address REXXVAR "Sort REXXVAR:line. to CONSOLE:"
  91.   
  92.              Types to the window:
  93.   
  94.                   at
  95.                   bat
  96.                   cat
  97.   
  98.              To put the values in another sorted stem array called
  99.              "sorted_lines.":
  100.   
  101.                   Address REXXVAR "Sort REXXVAR:line. to",
  102.                                        "REXXVAR:sorted_lines."
  103.   
  104.              Results in:
  105.   
  106.                   sorted_lines.0 = 3
  107.                   sorted_lines.1 = 'at'
  108.                   sorted_lines.2 = 'bat'
  109.                   sorted_lines.3 = 'cat'
  110.   
  111.          b.  stem array, any indices
  112.   
  113.              Please note the extra index, whose value is undefined.
  114.   
  115.                   line.AT = 'splat'
  116.                   line.BAT = 'acrobat'
  117.                   line.CAT = 'muskrat'
  118.                   indices = 'AT BAT CAT MAT'
  119.                   Address REXXVAR "Sort REXXVAR:line./nl/indices to CONSOLE:"
  120.   
  121.              yields:
  122.   
  123.                   acrobat
  124.                   LINE.MAT
  125.                   muskrat
  126.                   splat
  127.   
  128.              "LINE.MAT" was created because there is no default value for all stem
  129.              values (e.g., "line. = ''"), so the value of the stem array element
  130.              for index "MAX" is its name, by REXX rules.
  131.   
  132.          c.  variable value
  133.   
  134.                   var = 'cat bat at'
  135.                   Address REXXVAR "Sort REXXVAR:var to CONSOLE:"
  136.   
  137.              Types to the window:
  138.   
  139.                   at
  140.                   bat
  141.                   cat
  142.   
  143.              Note that input is delimited (by default) by spaces and the output is
  144.              delimited by newline characters. The newline character is what is
  145.              required on input by most text-based programs, so that is what each
  146.              delimited value changes to.  If we were to write to a variable
  147.              instead of the console:
  148.   
  149.                   var = 'cat bat at'
  150.                   Address REXXVAR "Sort REXXVAR:var to REXXVAR:sorted_var"
  151.                   Say sorted_var
  152.   
  153.              then the proper blank-delimited values would be seen:
  154.   
  155.                   at bat cat
  156.   
  157.              Newline characters are translated into spaces, by default.
  158.   
  159.      2.  Showing the values
  160.   
  161.          This is only useful for stem arrays, as REXX's "Say" command easily
  162.          handles the simple/compound variable's case.
  163.   
  164.          a.  integer indices
  165.   
  166.                   line.1 = 'cat'
  167.                   line.2 = 'bat'
  168.                   line.3 = 'at'
  169.                   line.0 = 3
  170.                   Address REXXVAR "Type REXXVAR:line."
  171.   
  172.              results in the following listing:
  173.   
  174.                   cat
  175.                   bat
  176.                   at
  177.   
  178.          b.  arbitrary indices
  179.   
  180.              Here is a more complicated example with arbitrary indices, and only a
  181.              subset of the possible values:
  182.   
  183.                   line.AT = 'splat'
  184.                   line.BAT = 'acrobat'
  185.                   line.CAT = 'muskrat'
  186.                   indices = 'CAT AT'
  187.                   Address REXXVAR "Type REXXVAR:line./nl/indices"
  188.   
  189.              yields:
  190.   
  191.                   muskrat
  192.                   splat
  193.   
  194.              Note that the indices are used in left-to-right order.
  195.   
  196.          c.  sorting the arbitrary indices
  197.   
  198.              The values are in index order ("AT" before "CAT"), not value order.
  199.   
  200.                   line.AT = 'splat'
  201.                   line.BAT = 'acrobat'
  202.                   line.CAT = 'muskrat'
  203.                   indices = 'CAT AT'
  204.                   Address REXXVAR "Sort REXXVAR:indices to",
  205.                                        "REXXVAR:sorted_indices"
  206.                   Address REXXVAR "Type REXXVAR:line./nl/sorted_indices"
  207.   
  208.              yields:
  209.   
  210.                   splat
  211.                   muskrat
  212.   
  213.      3.  Creating stem arrays from variable's value
  214.  
  215.          *** NOTE: Due to demo limitations, this may not work.
  216.   
  217.          Let's say you have the output from the rexxsupport.library's  SHOWLIST()
  218.          function, and you would like these items to be placed in a stem array:
  219.   
  220.               if show('L', 'rexxsupport.library') = 0
  221.                 then do
  222.                   if addlib('rexxsupport.library',0,-30,0) = 0
  223.                     then Exit 20
  224.                 end
  225.               /* Use slashes to separate since blanks may be in names */
  226.               assigns = showlist('A',,'/')
  227.               Address REXXVAR "Copy REXXVAR:assigns/sl to REXXVAR:assign."
  228.   
  229.          All of the assignment names, minus the delimiting slashes, would be
  230.          placed in integer-indexed "assign." stem array elements, and "assign.0"
  231.          would contain the number of elements.
  232.   
  233.          The reverse operation also works, creating a variable whose contents are
  234.          the stem array element's values. But be careful -- a single ARexx
  235.          variable can hold only about  65,000 characters: you could easily exceed
  236.          that limit with a large number of moderately-sized stem array elements or
  237.          a small number of large-sized elements. REXXVAR will only partially fill
  238.          the variable value in the case where the next amount of data would exceed
  239.          the limit.
  240.   
  241.      4.  Getting an environment variable value
  242.   
  243.          This is simple, and it should be, and is one of the reasons why RexxVar
  244.          exists.
  245.   
  246.               Address REXXVAR "Getenv >REXXVAR:wb_version Workbench"
  247.   
  248.      5.  Editing
  249.   
  250.          *** NOTE: Due to demo limitations, this will not work beyond
  251.                    24 lines of 24 characters apiece (maximum).
  252.  
  253.          One of the more interesting tasks that REXXVAR allows is the ability to
  254.          use your favorite editor (e.g., MEMACS) to view and modify the contents
  255.          of variables or stem array elements.  With this capability, you don't
  256.          have to write special windowing code just to change a few key values, and
  257.          you gain a familiar and full editing environment.
  258.   
  259.          For example, let's say your lines are in a stem array called "lines.",
  260.          appropriately integer-indexed, and you use the MEMACS editor:
  261.   
  262.               Address REXXVAR "MEMACS REXXVAR:lines."
  263.   
  264.          The editor will read in your stem array values as if it were reading a
  265.          file.  When you modify the file and save it, the editor replaces those
  266.          "lines." values with the new ones.
  267.   
  268.      6.  Searching
  269.   
  270.          To show the stem array elements that contain a particular substring, use
  271.          th AmigaDOS SEARCH command:
  272.   
  273.               line.AT = 'splat'
  274.               line.BAT = 'acrobat'
  275.               line.CAT = 'muskrat'
  276.               indices = 'CAT BAT AT'
  277.               Address REXXVAR "SEARCH REXXVAR:line./nl/indices bat"
  278.   
  279.          yields:
  280.   
  281.                  2 acrobat
  282.   
  283.          which means the second ("2") line passed to the Search command was where
  284.          it found a match, then it shows the value containing the match.
  285.   
  286.          What is even more interesting is that you can select which lines you want
  287.          to have searched -- just add indices to or remove them from the arbitrary
  288.          indices variable.  This ability to group different portions of the same
  289.          set of information can be invaluable in some applications.
  290.   
  291.      7.  Combining
  292.   
  293.          What if you want to combine two or more lists into one? Use JOIN:
  294.   
  295.               first_list.1 = 'c'
  296.               first_list.2 = 'd'
  297.               first_list.0 = 2
  298.               second_list.1 = 'a'
  299.               second_list.2 = 'b'
  300.               second_list.0 = 2
  301.               Address REXXVAR "JOIN REXXVAR:first_list. REXXVAR:second_list.",
  302.                       "to REXXVAR:big_list."
  303.   
  304.          would yield:
  305.   
  306.               big_list.1 = 'c'
  307.               big_list.2 = 'd'
  308.               big_list.3 = 'a'
  309.               big_list.4 = 'b'
  310.               big_list.0 = 4
  311.   
  312.          You could also mix variable values with actual file contents.
  313.   
  314.          Splitting one file into pieces is another story... MultiVol (another
  315.          product of AugmenTek) may be able to address this (this experiment has
  316.          not been attempted, but it should, in theory, work).
  317.   
  318.      8.  Managing Files and Directories
  319.   
  320.          *** NOTE: Due to demo limitations, this may not work.
  321.  
  322.          Many times you want to do something with a group of files. The AmigaDOS
  323.          2.0 LIST command's enhancements have helped tremendously with making an
  324.          executable file from a special list of files, output in a special format
  325.          (LFORMAT).  Pattern-matching helps select groups of files.
  326.   
  327.          Sometimes, however, you want more control over the processing than simply
  328.          executing the command on each file.  But how do you get the nice
  329.          pattern-matched output from LIST into an ARexx program?
  330.   
  331.               Address REXXVAR "List quick nohead #?.[c|h] to REXXVAR:file."
  332.   
  333.          You can also insert an LFORMAT string in there to get more information,
  334.          such as the complete path name.  This helps a lot with the
  335.          multiple-assign lists, which few programs support.
  336.   
  337.      9.  Get the amount of free space on a disk
  338.   
  339.          *** NOTE: Due to demo limitations, this may not work.
  340.  
  341.               name = 'DF0:'
  342.               Address REXXVAR "info >REXXVAR:disk_info" name
  343.               Parse var disk_info . (name) . . free_space .
  344.               Say name 'has' free_space 'blocks of free space.'
  345.   
  346.      10. Opening a new shell
  347.   
  348.          Sometimes it is useful to open up your a shell, often executing a
  349.          specific set of commands before opening it.  Without REXXVAR, you would
  350.          have to create a file, probably in RAM, then pass that temporary file to
  351.          Newshell to use.  With REXXVAR, no temporary file is needed:
  352.   
  353.               startup = 'Echo "Hi!"\CD RAM:\CD'
  354.               Address REXXVAR "Newshell CON:10/10/640/100/MyShell/AUTO",
  355.                               "from REXXVAR:startup/\"
  356.   
  357.      11. Passing data between ARexx programs
  358.   
  359.          You could always use clip lists, temporary files, messages, and
  360.          environment variables to do this.  However, clip lists need to be
  361.          interpreted to assign values, temporary files are a nuisance to code for
  362.          reading and writing, messages are too complicated for simple uses, and
  363.          environment variables are unwieldy and are limited in size.
  364.   
  365.          It's far easier just to use this in an ARexx program running in one
  366.          shell/process:
  367.   
  368.               Address REXXVAR "copy rexxvar:shared_info. pipe:a"
  369.   
  370.          and in another ARexx program in another shell/process use:
  371.   
  372.               Address REXXVAR "copy pipe:a rexxvar:new_info."
  373.   
  374.          You could use different named pipes for different variables. Or you could
  375.          pass a variable containing arbitrary indices, then pass the stem array
  376.          values for it -- the indices may be more meaningful to the receiving
  377.          program than numeric ones.
  378.   
  379.      It is generally not advisable to use the same stem array name or variable
  380.      name for both input and output unless you know that the input is completely
  381.      read before anything is output (as in an Editor).
  382.   
  383.  
  384.